git clone git://github.com/picketlink2/picketlink-quickstarts.git
This guide will help you getting started using some examples provided by PicketLink.
Before continue, make sure you have configured properly PicketLink in your JBoss AS 7 distribution. For more information about how to install/configure PicketLink using JBoss AS 7 see this section.
The PicketLink Quickstarts provides some useful examples using PicketLink Federation. The examples are organized per federation protocol. PicketLink currently supports the following:
Security Assertion Markup Language v2 (SAML)
WS-Trust
eXtensible Access Control Markup Language (XACML)
The SAML examples helps you to understand how to configure and run a Identity Provider or Service Provider. These examples can be used for you to construct your own implementations.
The table bellow lists the Identity Providers examples provided:
Name |
Description |
URL |
idp |
Simple Identity Provider implementation |
http://\[server\]:\[port\]/idp |
idp-sig |
Identity Provider with digital
signature
support for SAML assertions. All the comunication between IDP and
|
http://\[server\]:\[port\]/idp-sig |
idp-enc |
Identity Provider with digital signature and encryption support for SAML assertions. |
http://\[server\]:\[port\]/idp-enc\\ |
idp-metadata |
Identity Provider using with SAML Metadata Support |
http://\[server\]:\[port\]/idp-metadata\\\\ |
The table bellow lists the Service Providers examples provided:
Name |
Description |
URL |
sales-post |
Service Provider using HTTP POST Binding |
http://\[server\]:\[port\]/sales-post\\ |
sales-post-sig |
Service Provider using HTTP POST Binding with digital signature support for SAML assertions |
http://\[server\]:\[port\]/sales-post-sig\\ |
sales-metadata |
Service Provider using SAML Metadata Support |
http://\[server\]:\[port\]/sales-metadata\\\\ |
employee |
Service Provider using HTTP REDIRECT Binding |
http://\[server\]:\[port\]/employee\\ |
employee-sig |
Service Provider using HTTP REDIRECT Binding with digital signature support for SAML assertions |
http://\[server\]:\[port\]/employee-sig\\ |
You can use any of these examples, according with your needs. If you just want to understand how PicketLink SAML Support works you should start using the examples using HTTP Redirect Binding. They can help you a lot understanding how works the communication between IDP and SPs.
These examples are very simple and helps only to demonstrate how you can configure your own implementation of Identity Providers and Service Providers.
It is important to have in mind that choosing a example with digital signature support, both IDP and SP must have this feature enabled.
Eg.: idp-sig and employee-sig/sales-post-sig.
Actually, the WS-Trust Security Token Service implementation is more than a quickstart is a fully compliant WS-Trust implementation using SAML tokens.
The table bellow lists the Service Providers examples provided:
Name |
Description |
URL |
picketlink-sts |
Fully compliant WS-Trust Security Token Service implementation |
http://\[server\]:\[port\]/picketlink-sts/PicketLinkSTS?wsdl\\ |
You can use the PicketLink STS to leverage your federation to your service layer: Web Service and EJBs, for example.
PicketLink provides a default implementation for a XACML PDP. It is responsible to evaluates and issues authorization decisions.
The table bellow lists the Service Providers examples provided:
Name |
Description |
URL |
pdp |
Fully compliant XACML Web Service |
http://\[server\]:\[port\]/pdp/SOAPSAMLXACMLPDP?wsdl |
PicketLink needs to get running in different servers/containers:
JBoss Application Server 5
JBoss Application Server 7
Apache Tomcat 6
To achieve that the PicketLink project is organized in bindings where each binding refers to a specific target server or container.
The link above allows you to download all the available distribution packages with all the examples provided. The distribution package is specific for each binding or target server.
Name |
Description |
picketlink-quickstarts-VERSION-webapps-jboss-as5.zip |
All the examples configured for JBoss AS5 |
picketlink-quickstarts-VERSION-webapps-jboss-as7.zip |
All the examples configured for JBoss AS7 |
picketlink-quickstarts-VERSION-webapps-tomcat-6.zip |
All the examples configured for Apache Tomcat 6 |
If you want to build the upstream version (SNAPSHOT) you need to clone and build first the PicketLink Federaton workspace. You can clone this repo from:
The quickstarts are provided as a project in github:
Follow these steps to get the quickstarts locally:
1. Clone the project from github.
git clone git://github.com/picketlink2/picketlink-quickstarts.git
2. Enter in the directory picketlink-quickstarts and execute a maven build:
cd picketlink-quickstarts mvn clean install
3. If your build was successful you should have a zip file with all examples packaged in a file called picketlink-quickstarts/target/picketlink-webapps-jboss-as7.zip.
As default, the quickstarts are configured and packaged for JBoss AS 7. For more information about how to package the quickstarts for different containers/bindings see the next section.
The master branch is our development branch. If you are looking for a specific version we recommend to checkout a specific tag.
For example, if you want the 2.1.4.Final version you can use the https://github.com/picketlink2/picketlink-quickstarts/tree/v2.1.4.Final tag.
To switch to a tag use the following git command:
git checkout v2.1.4.Final
See the section Deploying the Quickstarts to know how to deploy the packaged applications.
The quickstarts can be used in any of the available bindings/target servers, you just need to change the parameter -Dbinding and -Dbinding-version according to your needs.
The table above lists all possible combinations and supported values for both parameters:
binding |
binding-version |
Description |
jboss |
as5 |
mvn -Dbinding=jboss -Dbinding-version=as5 clean install, to build for JBoss AS 5 |
jboss |
as7 |
mvn -Dbinding=jboss -Dbinding-version=as7 clean install, to build for JBoss AS 7 |
tomcat |
6 |
mvn -Dbinding=tomcat -Dbinding-version=6 clean install, to build for Apache Tomcat 6 |
To build the quickstarts for one of the supported bindings use the following mvn command:
cd picketlink-quickstarts mvn -Dbinding=jboss -Dbinding-version=as5 clean install
The command above will configure and package the quickstarts for deployment in JBoss AS 5. Use the values from the table above to change the parameters -Dbinding and -Dbinding-version.
Before running the examples, you must add the following security-domain configurations to your standalone.xml:
<subsystem xmlns="urn:jboss:domain:security:1.0">
<security-domains>
...
<security-domain name="idp" cache-type="default">
<authentication>
<login-module code="UsersRoles" flag="required">
<module-option name="usersProperties" value="users.properties" />
<module-option name="rolesProperties" value="roles.properties" />
</login-module>
</authentication>
</security-domain>
<security-domain name="picketlink-sts" cache-type="default">
<authentication>
<login-module code="UsersRoles" flag="required">
<module-option name="usersProperties" value="users.properties" />
<module-option name="rolesProperties" value="roles.properties" />
</login-module>
</authentication>
</security-domain>
<security-domain name="sp" cache-type="default">
<authentication>
<login-module code="org.picketlink.identity.federation.bindings.jboss.auth.SAML2LoginModule" flag="required"/>
</authentication>
</security-domain>
...
</security-domains>
</subsystem>
These are very important configurations given that they define how both IDP, STS and SP should authenticate users. Usually you would configure your own configuration for the security domains to load users and roles from a LDAP or database, for example. The configurations above are only useful to show what do you need to configure in order to authenticate users.
You may notice that the security domain configuration for the IDP and STS references two properties files: user.properties and roles.properties. Both files are inside the WAR of the deployed IDP. These files are used to authenticate users and load the roles.
All you need to deploy the quickstarts is unzip the distribution package (generated during the build, as described before) to the [jboss.server.base.dir]/standalone/deployments.
To run the quickstarts start your JBoss Application Server 7 instance. Open your browser and enter the URL of the application do you want to use.
For a complete list of the URLs for each example application take a look at the table for the SAML, WS-Trust and XAML sections.
//TODO: Show how to setup a workspace using Eclipse for the quickstarts.